From d7915fbca825924b098c5339a0b5c8048d774187 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 19 Jun 2021 12:23:27 -0700 Subject: [PATCH] docs: Add a section about Drag-and-Drop --- docs/reference/gtk/drag-and-drop.md | 54 +++++++++++++++++++++++++++++ docs/reference/gtk/gtk4.toml.in | 1 + 2 files changed, 55 insertions(+) create mode 100644 docs/reference/gtk/drag-and-drop.md diff --git a/docs/reference/gtk/drag-and-drop.md b/docs/reference/gtk/drag-and-drop.md new file mode 100644 index 0000000000..15370f1655 --- /dev/null +++ b/docs/reference/gtk/drag-and-drop.md @@ -0,0 +1,54 @@ +Title: Drag-and-Drop in GTK + +Drag-and-Drop (DND) is a user interaction pattern where users drag a UI element +from one place to another, either inside a single application or between +different application windows. + +When the element is 'dropped', data is transferred from the source to the +destination, according to the drag action that is negotiated between both +sides. Most commonly, that is a _copy_, but it can also be a _move_ or a +_link_, depending on the kind of data and how the drag operation has been +set up. + +This chapter gives an overview over how Drag-and-Drop is handled with event +controllers in GTK. + +## Drag sources + +To make data available via DND, you create a [class@Gtk.DragSource]. Drag sources +are event controllers, which initiate a Drag-and-Drop operation when the user clicks +and drags the widget. + +A drag source can be set up ahead of time, with the desired drag action(s) and the data +to be transferred. But it is also possible to provide the data when a drag operation +is about to begin, by connecting to the [signal@Gtk.DragSource::prepare] signal. + +The GtkDragSource emits the [signal@Gtk.DragSource::drag-begin] signal when the DND +operation starts, and the [signal@Gtk.DragSource::drag-end] signal when it is done. +But it is not normally necessary to handle these signals. One case in which a ::drag-end +handler is necessary is to implement `GDK_ACTION_MOVE`. + +## Drop targets + +To receive data via DND, you create a [class@Gtk.DropTarget], and tell it what kind of +data to accept. You need to connect to the [signal@Gtk.DropTarget::drop] signal to receive +the data when a DND operation occurs. + +While a DND operation is ongoing, GTK provides updates when the pointer moves over +the widget to which the drop target is associated. The [signal@Gtk.DropTarget::enter], +[signal@Gtk.DropTarget::leave] and [signal@Gtk.DropTarget::motion] signals get emitted +for this purpose. + +GtkDropTarget provides a simple API, and only provides the data when it has been completely +transferred. If you need to handle the data transfer yourself (for example to provide progress +information during the transfer), you can use the more complicated [class@Gtk.DropTargetAsync]. + +## Other considerations + +It is sometimes necessary to update the UI of the destination while a DND operation is ongoing, +say to scroll or expand a view, or to switch pages. Typically, such UI changes are triggered +by hovering over the widget in question. + +[class@Gtk.DropControllerMotion] is an event controller that can help with implementing such +behaviors. It is very similar to [class@Gtk.EventControllerMotion], but provides events during +a DND operation. diff --git a/docs/reference/gtk/gtk4.toml.in b/docs/reference/gtk/gtk4.toml.in index 2a0d57e922..e1cc9f34cb 100644 --- a/docs/reference/gtk/gtk4.toml.in +++ b/docs/reference/gtk/gtk4.toml.in @@ -57,6 +57,7 @@ content_files = [ "initialization.md", "actions.md", "input-handling.md", + "drag-and-drop.md", "drawing-model.md", "css-overview.md", "css-properties.md", -- 2.30.2